Description

This PR implements a new review step for the Smart Linking feature in the Parse.ly Plugin. It introduces a modal where all new link suggestions and existing smart links are visible together, and can be reviewed from a single place.

This is part 1 of the new Smart Linking feature, focusing primarily on the UI/UX. Part 2, which will implement a backend to persistently store smart links, will be coming next.

The New Review Modal

This PR introduces several new components. To help understand this new implementation, here is a breakdown of the modal into its individual components.

ReviewModalSidebar

The ReviewModalSidebar component provides users with an organized list of all the smart links within a review modal. This sidebar makes it easy to navigate through each linkable word or phrase by displaying them in a clear, scrollable list.

Users can click on any link to view its details, and the sidebar automatically scrolls to keep the selected link in view. Each link item shows its text and indicates whether the link is new and unapplied. This functionality helps users efficiently review and manage their smart links, ensuring they can easily identify and select the most relevant links for their content.

The items on the sidebar are always ordered - the sorting is managed by the Smart Linking store directly, where new suggestions are on the top, and existing smart links are on the bottom. On top of this sorting, the links are also ordered by when the occur in the post content.

ReviewSuggestion

The ReviewSuggestion component provides an interface for reviewing individual smart link suggestions. It allows users to navigate through the list of suggestions, view the context within which each link appears, and make decisions on whether to accept, reject, or modify the suggested links.

Key Functionalities:

• Breadcrumb Navigation: Displays the hierarchical path of blocks leading to the block containing the link, helping users understand the link's context within the content structure.
• Block Preview: Renders a non-editable preview of the block where the link is found, with the link highlighted to draw attention.
• Link Details: Shows detailed information about the link, including its display URL and the type of post it links to (internal or external).
• Control Buttons: Provides navigation controls to move to the next or previous suggestions, and actions to accept, reject, or remove the link. If a link is already applied, users can also select it in the editor for further modifications.

Existing Smart Links

When opening a post, the Parse.ly Content Helper (PCH) needs to identify the existing Smart Links within the content. This is achieved using a custom data attribute included with all smart links: data-smartlink. The value of this attribute is the Smart Link UID, which uniquely identifies each link in the content.

The PCH scans the post content to find all anchor (<a>) tags that contain the data-smartlink attribute. By extracting the UID from each of these tags, it builds a comprehensive list of existing Smart Links. This method ensures that all Smart Links can be managed effectively, even if the block editor has been closed and reopened. This functionality allows users to seamlessly maintain and update their Smart Links across editing sessions, ensuring that the content remains connected and relevant.

Fixing and Validating Smart Links

When opening a post, the PCH needs to ensure that the store is synchronized with the actual post content. This can become challenging when a smart link is edited because the data-smartlink attribute, which is not included in the Link allowlist, gets stripped during the editing process.

The LinkMonitor component plays a important role in addressing this issue. It continuously listens for changes in smart links—whether new links are added, existing links are removed, or links are edited. When it detects that a smart link has been modified and the data-smartlink attribute has been unintentionally removed, it parses the content and attempts to re-add the missing data-smartlink attribute, thereby preserving the unique identifier of the smart link.

Additionally, there is a validation and fixing step implemented during the post save process. This ensures that all smart links are validated and any missing data-smartlink attributes are restored, preventing the loss of any smart links. This comprehensive validation process guarantees that the integrity of smart links is maintained throughout the content lifecycle, even after multiple edits and saves.

Getting the Post Type from a URL

To populate the type of the post in the Link Details section, PCH uses the url_to_post_type endpoint. This endpoint processes a given URL and returns the corresponding post type, ensuring accurate identification of linked content.

When a URL is submitted to the endpoint, the PCH retrieves the post ID associated with the URL using caching and available WordPress functions. If the post ID is found, the function fetches and returns the post type. This allows the plugin to provide relevant post type information in the Link Details section, enhancing the management and validation of smart links.

Here's some quick documentation about this endpoint:

Endpoint: /smart-linking/url-to-post-type
Method: POST
Request Parameters: url (string) - The URL to determine the post type.
Response: post_id (int), post_type (string)

Motivation and context

This new version addresses several limitations and introduces new capabilities to make the feature more robust and user-friendly. It solves the problem of manual link management by providing smarter, more contextually relevant suggestions, thereby saving time and effort for content creators.

It addresses a few open issues:

• Closes Fix issue with numAddedLinks state in Smart Linking component #2400
• Closes PCH: show list of smart links generated #2173

How has this been tested?

This have been thoroughly tested in my local environment, with different types of content. However, this is still experimental, so I appreciate if you try to break it 😄

Video demo

Summary by CodeRabbit

• New Features

  • Introduced a Smart_Linking_Endpoint class for managing smart links, including URL conversion and availability checks.
  • Added a Smart_Link class to represent smart link suggestions with methods for serialization, deserialization, and saving.
  • Implemented a LinkMonitor component to detect smart link changes in the WordPress editor.
  • Added a ReviewModalSidebar component for interacting with smart links within the review modal interface.

• Enhancements

  • Updated various methods to accept a request parameter for enhanced functionality.
  • Added new CSS base units, selectors, and color variables for improved styling options.
  • Improved validation of smart links before saving posts to ensure content integrity.